21 серпня 2025 р.Українська

Глибокий аналіз декораторів JavaScript: синтаксис, випадки використання для метапрограмування, найкращі практики та вплив на підтримку коду. Містить практичні приклади.

Декоратори JavaScript: Реалізація метапрограмування

Декоратори JavaScript — це потужна функція, яка дозволяє додавати метадані та змінювати поведінку класів, методів, властивостей і параметрів декларативним способом, що підтримує повторне використання. Вони є пропозицією 3-ї стадії в процесі стандартизації ECMAScript і широко використовуються з TypeScript, який має власну (трохи відмінну) реалізацію. Ця стаття надасть вичерпний огляд декораторів JavaScript, зосереджуючись на їхній ролі в метапрограмуванні та ілюструючи їх використання на практичних прикладах.

Що таке декоратори JavaScript?

Декоратори — це патерн проєктування, який розширює або змінює функціональність об'єкта, не змінюючи його структури. У JavaScript декоратори — це спеціальні види оголошень, які можна приєднувати до класів, методів, аксесорів, властивостей або параметрів. Вони використовують символ @, за яким слідує функція, що буде виконана під час визначення декорованого елемента.

Думайте про декоратори як про функції, які приймають декорований елемент як вхідні дані та повертають змінену версію цього елемента або виконують певний побічний ефект на його основі. Це забезпечує чистий та елегантний спосіб додавання функціональності без прямої зміни вихідного класу чи функції.

Ключові поняття:

Функція-декоратор: Функція, перед якою стоїть символ @. Вона отримує інформацію про декорований елемент і може його змінювати.
Декорований елемент: Клас, метод, аксесор, властивість або параметр, до якого застосовано декоратор.
Метадані: Дані, що описують інші дані. Декоратори часто використовуються для зв'язування метаданих з елементами коду.

Синтаксис та структура

Основний синтаксис декоратора такий:

@decorator
class MyClass {
  // Class members
}

Тут @decorator — це функція-декоратор, а MyClass — декорований клас. Функція-декоратор викликається під час визначення класу і може отримувати доступ до визначення класу та змінювати його.

Декоратори також можуть приймати аргументи, які передаються самій функції-декоратору:

@loggable(true, "Custom Message")
class MyClass {
  // Class members
}

У цьому випадку loggable — це фабрика декораторів, яка приймає аргументи та повертає власне функцію-декоратор. Це дозволяє створювати більш гнучкі та конфігуровані декоратори.

Типи декораторів

Існують різні типи декораторів, залежно від того, що вони декорують:

Декоратори класів: Застосовуються до класів.
Декоратори методів: Застосовуються до методів усередині класу.
Декоратори аксесорів: Застосовуються до гетерів та сетерів.
Декоратори властивостей: Застосовуються до властивостей класу.
Декоратори параметрів: Застосовуються до параметрів методу.

Декоратори класів

Декоратори класів використовуються для зміни або розширення поведінки класу. Вони отримують конструктор класу як аргумент і можуть повернути новий конструктор для заміни оригінального. Це дозволяє додавати таку функціональність, як логування, впровадження залежностей або управління станом.

Приклад:

function loggable(constructor: Function) {
  console.log("Class " + constructor.name + " was created.");
}

@loggable
class User {
  name: string;

  constructor(name: string) {
    this.name = name;
  }
}

const user = new User("Alice"); // Виводить: Class User was created.

У цьому прикладі декоратор loggable виводить повідомлення в консоль щоразу, коли створюється новий екземпляр класу User. Це може бути корисно для налагодження або моніторингу.

Декоратори методів

Декоратори методів використовуються для зміни поведінки методу всередині класу. Вони отримують такі аргументи:

target: Прототип класу.
propertyKey: Назва методу.
descriptor: Дескриптор властивості для методу.

Дескриптор дозволяє отримувати доступ до поведінки методу та змінювати її, наприклад, обгортаючи його додатковою логікою або повністю перевизначаючи.

Приклад:

function logMethod(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;

  descriptor.value = function (...args: any[]) {
    console.log(`Calling method ${propertyKey} with arguments: ${args}`);
    const result = originalMethod.apply(this, args);
    console.log(`Method ${propertyKey} returned: ${result}`);
    return result;
  };
  return descriptor;
}

class Calculator {
  @logMethod
  add(a: number, b: number): number {
    return a + b;
  }
}

const calculator = new Calculator();
const sum = calculator.add(5, 3); // Виводить логи про виклик методу та значення, що повертається

У цьому прикладі декоратор logMethod логує аргументи методу та значення, що повертається. Це може бути корисно для налагодження та моніторингу продуктивності.

Декоратори аксесорів

Декоратори аксесорів схожі на декоратори методів, але застосовуються до гетерів та сетерів. Вони отримують ті ж аргументи, що й декоратори методів, і дозволяють змінювати поведінку аксесора.

Приклад:

function validate(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalSet = descriptor.set;

  descriptor.set = function (value: any) {
    if (value < 0) {
      throw new Error("Value must be non-negative.");
    }
    originalSet.call(this, value);
  };
}

class Temperature {
  private _celsius: number;

  constructor(celsius: number) {
    this._celsius = celsius;
  }

  @validate
  set celsius(value: number) {
    this._celsius = value;
  }

  get celsius(): number {
    return this._celsius;
  }
}

const temperature = new Temperature(25);
temperature.celsius = 30; // Валідно
// temperature.celsius = -10; // Викидає помилку

У цьому прикладі декоратор validate гарантує, що значення температури не є від'ємним. Це може бути корисним для забезпечення цілісності даних.

Декоратори властивостей

Декоратори властивостей використовуються для зміни поведінки властивості класу. Вони отримують такі аргументи:

target: Прототип класу (для властивостей екземпляра) або конструктор класу (для статичних властивостей).
propertyKey: Назва властивості.

Декоратори властивостей можна використовувати для визначення метаданих або зміни дескриптора властивості.

Приклад:

function readonly(target: any, propertyKey: string) {
  Object.defineProperty(target, propertyKey, {
    writable: false,
  });
}

class Configuration {
  @readonly
  apiUrl: string = "https://api.example.com";
}

const config = new Configuration();
// config.apiUrl = "https://newapi.example.com"; // Викидає помилку в суворому режимі

У цьому прикладі декоратор readonly робить властивість apiUrl доступною тільки для читання, запобігаючи її зміні після ініціалізації. Це може бути корисно для визначення незмінних конфігураційних значень.

Декоратори параметрів

Декоратори параметрів використовуються для зміни поведінки параметра методу. Вони отримують такі аргументи:

target: Прототип класу (для методів екземпляра) або конструктор класу (для статичних методів).
propertyKey: Назва методу.
parameterIndex: Індекс параметра у списку параметрів методу.

Декоратори параметрів використовуються рідше, ніж інші типи декораторів, але вони можуть бути корисними для валідації вхідних параметрів або впровадження залежностей.

Приклад:

function required(target: any, propertyKey: string, parameterIndex: number) {
  const existingRequiredParameters: number[] = Reflect.getOwnMetadata(propertyKey, target, "required") || [];
  existingRequiredParameters.push(parameterIndex);
  Reflect.defineMetadata(propertyKey, existingRequiredParameters, target, "required");
}

function validateMethod(target: any, propertyName: string, descriptor: PropertyDescriptor) {
  let method = descriptor.value!;

  descriptor.value = function () {
    let requiredParameters: number[] = Reflect.getOwnMetadata(propertyName, target, "required");
    if (requiredParameters) {
      for (let parameterIndex of requiredParameters) {
        if (arguments[parameterIndex] === null || arguments[parameterIndex] === undefined) {
          throw new Error(`Missing required argument at index ${parameterIndex}`);
        }
      }
    }

    return method.apply(this, arguments);
  };
}


class ArticleService {
  create(
    @required title: string,
    @required content: string
  ): void {
    console.log(`Creating article with title: ${title} and content: ${content}`);
  }
}

const service = new ArticleService();
// service.create("My Article", null); // Викидає помилку
service.create("My Article", "Article Content"); // Валідно

У цьому прикладі декоратор required позначає параметри як обов'язкові, а декоратор validateMethod гарантує, що ці параметри не є null або undefined. Це може бути корисним для забезпечення валідації вхідних даних методу.

Метапрограмування з декораторами

Одним з найпотужніших способів використання декораторів є метапрограмування. Метадані — це дані про дані. У контексті програмування це дані, які описують структуру, поведінку та призначення вашого коду. Декоратори надають чистий та декларативний спосіб асоціювати метадані з класами, методами, властивостями та параметрами.

Reflect Metadata API

Reflect Metadata API — це стандартний API, який дозволяє зберігати та отримувати метадані, пов'язані з об'єктами. Він надає такі функції:

Reflect.defineMetadata(key, value, target, propertyKey): Визначає метадані для конкретної властивості об'єкта.
Reflect.getMetadata(key, target, propertyKey): Отримує метадані для конкретної властивості об'єкта.
Reflect.hasMetadata(key, target, propertyKey): Перевіряє, чи існують метадані для конкретної властивості об'єкта.
Reflect.deleteMetadata(key, target, propertyKey): Видаляє метадані для конкретної властивості об'єкта.

Ви можете використовувати ці функції разом з декораторами, щоб пов'язувати метадані з елементами вашого коду.

Приклад: Визначення та отримання метаданих

import 'reflect-metadata';

const logKey = "log";

function log(message: string) {
  return function (target: any, key: string, descriptor: PropertyDescriptor) {
    Reflect.defineMetadata(logKey, message, target, key);

    const originalMethod = descriptor.value;
    descriptor.value = function (...args: any[]) {
      console.log(Reflect.getMetadata(logKey, target, key));
      const result = originalMethod.apply(this, args);
      return result;
    }

    return descriptor;
  }
}

class Example {
  @log("Executing method")
  myMethod(arg: string): string {
    return `Method called with ${arg}`;
  }
}

const example = new Example();
example.myMethod("Hello"); // Виводить: Executing method, Method called with Hello

У цьому прикладі декоратор log використовує Reflect Metadata API для зв'язування повідомлення логу з методом myMethod. Коли метод викликається, декоратор отримує та виводить це повідомлення в консоль.

Сфери застосування метапрограмування

Метапрограмування з декораторами має багато практичних застосувань, зокрема:

Серіалізація та десеріалізація: Анотуйте властивості метаданими, щоб контролювати, як вони серіалізуються або десеріалізуються в/з JSON чи інших форматів. Це може бути корисним при роботі з даними із зовнішніх API або баз даних, особливо в розподілених системах, що вимагають перетворення даних між різними платформами (наприклад, конвертація форматів дат між різними регіональними стандартами). Уявіть собі платформу електронної комерції, що працює з міжнародними адресами доставки, де ви можете використовувати метадані для визначення правильного формату адреси та правил валідації для кожної країни.
Впровадження залежностей: Використовуйте метадані для ідентифікації залежностей, які потрібно впровадити в клас. Це спрощує управління залежностями та сприяє слабкому зв'язуванню. Розглянемо архітектуру мікросервісів, де сервіси залежать один від одного. Декоратори та метадані можуть полегшити динамічне впровадження клієнтів сервісів на основі конфігурації, що дозволяє легше масштабувати систему та підвищувати її відмовостійкість.
Валідація: Визначайте правила валідації як метадані та використовуйте декоратори для автоматичної перевірки даних. Це забезпечує цілісність даних та зменшує кількість шаблонного коду. Наприклад, глобальному фінансовому застосунку потрібно відповідати різним регіональним фінансовим регуляціям. Метадані можуть визначати правила валідації для форматів валют, розрахунків податків та лімітів транзакцій залежно від місцезнаходження користувача, забезпечуючи відповідність місцевим законам.
Маршрутизація та проміжне ПЗ (Middleware): Використовуйте метадані для визначення маршрутів та проміжного ПЗ для вебзастосунків. Це спрощує конфігурацію вашого застосунку та робить його більш зручним для підтримки. Глобально розподілена мережа доставки контенту (CDN) може використовувати метадані для визначення політик кешування та правил маршрутизації на основі типу контенту та місцезнаходження користувача, оптимізуючи продуктивність та зменшуючи затримки для користувачів у всьому світі.
Авторизація та автентифікація: Пов'язуйте ролі, дозволи та вимоги до автентифікації з методами та класами, полегшуючи декларативні політики безпеки. Уявіть собі транснаціональну корпорацію зі співробітниками в різних відділах та локаціях. Декоратори можуть визначати правила контролю доступу на основі ролі, відділу та місцезнаходження користувача, гарантуючи, що тільки авторизований персонал може отримати доступ до конфіденційних даних та функціональності.

Найкращі практики

При використанні декораторів JavaScript варто дотримуватися таких найкращих практик:

Зберігайте декоратори простими: Декоратори мають бути сфокусованими та виконувати одне, чітко визначене завдання. Уникайте складної логіки всередині декораторів, щоб підтримувати читабельність та зручність обслуговування.
Використовуйте фабрики декораторів: Використовуйте фабрики декораторів, щоб створювати конфігуровані декоратори. Це робить ваші декоратори більш гнучкими та придатними для повторного використання.
Уникайте побічних ефектів: Декоратори повинні переважно зосереджуватися на зміні декорованого елемента або пов'язуванні з ним метаданих. Уникайте виконання складних побічних ефектів у декораторах, оскільки це може ускладнити розуміння та налагодження коду.
Використовуйте TypeScript: TypeScript надає чудову підтримку для декораторів, включаючи перевірку типів та IntelliSense. Використання TypeScript може допомогти вам виявляти помилки на ранніх етапах та покращити досвід розробки.
Документуйте свої декоратори: Чітко документуйте свої декоратори, щоб пояснити їхнє призначення та спосіб використання. Це полегшить іншим розробникам розуміння та правильне використання ваших декораторів.
Враховуйте продуктивність: Хоча декоратори є потужним інструментом, вони також можуть впливати на продуктивність. Пам'ятайте про наслідки для продуктивності ваших декораторів, особливо в критично важливих для швидкодії застосунках.

Приклади інтернаціоналізації з декораторами

Декоратори можуть допомогти в інтернаціоналізації (i18n) та локалізації (l10n), пов'язуючи дані та поведінку, специфічні для локалі, з компонентами коду:

Приклад: Локалізоване форматування дати

import 'reflect-metadata';

interface DateFormatOptions {
  locale: string;
  options?: Intl.DateTimeFormatOptions;
}

const dateFormatKey = 'dateFormat';

function formatDate(options: DateFormatOptions) {
  return function(target: any, propertyKey: string) {
    Reflect.defineMetadata(dateFormatKey, options, target, propertyKey);
  };
}

class Event {
  @formatDate({ locale: 'fr-FR', options: { year: 'numeric', month: 'long', day: 'numeric' } })
  startDate: Date;

  constructor(startDate: Date) {
    this.startDate = startDate;
  }

  getFormattedStartDate(): string {
    const options: DateFormatOptions = Reflect.getMetadata(dateFormatKey, Object.getPrototypeOf(this), 'startDate');
    return this.startDate.toLocaleDateString(options.locale, options.options);
  }
}

const event = new Event(new Date());
console.log(event.getFormattedStartDate()); // Виводить дату у французькому форматі

Приклад: Форматування валюти на основі місцезнаходження користувача

import 'reflect-metadata';

interface CurrencyFormatOptions {
  locale: string;
  currency: string;
}

const currencyFormatKey = 'currencyFormat';

function formatCurrency(options: CurrencyFormatOptions) {
  return function(target: any, propertyKey: string) {
    Reflect.defineMetadata(currencyFormatKey, options, target, propertyKey);
  };
}

class Product {
  @formatCurrency({ locale: 'de-DE', currency: 'EUR' })
  price: number;

  constructor(price: number) {
    this.price = price;
  }

  getFormattedPrice(): string {
    const options: CurrencyFormatOptions = Reflect.getMetadata(currencyFormatKey, Object.getPrototypeOf(this), 'price');
    return this.price.toLocaleString(options.locale, { style: 'currency', currency: options.currency });
  }
}

const product = new Product(99.99);
console.log(product.getFormattedPrice()); // Виводить ціну в німецькому форматі євро

Майбутні перспективи

Декоратори JavaScript — це функція, що розвивається, і стандарт все ще перебуває в розробці. Деякі майбутні аспекти включають:

Стандартизація: Стандарт ECMAScript для декораторів все ще в процесі розробки. У міру розвитку стандарту можуть відбуватися зміни в синтаксисі та поведінці декораторів.
Оптимізація продуктивності: У міру того, як декоратори ставатимуть все більш поширеними, виникне потреба в оптимізації продуктивності, щоб гарантувати, що вони не впливають негативно на швидкодію застосунків.
Підтримка інструментів: Покращена підтримка інструментів для декораторів, таких як інтеграція з IDE та інструменти для налагодження, полегшить розробникам ефективне використання декораторів.

Висновок

Декоратори JavaScript — це потужний інструмент для реалізації метапрограмування та розширення поведінки вашого коду. Використовуючи декоратори, ви можете додавати функціональність чистим, декларативним способом, що підтримує повторне використання. Це призводить до створення коду, який легше підтримувати, тестувати та масштабувати. Розуміння різних типів декораторів та способів їх ефективного використання є важливим для сучасної розробки на JavaScript. Декоратори, особливо в поєднанні з Reflect Metadata API, відкривають широкий спектр можливостей, від впровадження залежностей та валідації до серіалізації та маршрутизації, роблячи ваш код більш виразним та легким в управлінні.